The Pilot program is the basic driver for CUBE Voyager application programs, but it is also a calculator by itself. Most users will use Pilot only to invoke the individual programs in the order desired. Pilot can check the return codes of the individual programs, invoke system commands, and even perform complex mathematical computations, either for its own use or to pass on to the application programs. Through the use of loops and conditional branching, application programs can be run in any order desired.

This section discusses:

• Ouput files

• Process

• Statement tokens (%…% and @…@)

Output File

A project file, pppp.PRJ, is maintained (generated, if necessary) in the working sub-directory. It contains certain values that help the program to establish unique project identifications between applications that are run at separate times, and those that might be run simultaneously in a separate thread in a multitasking environment. Each application run generates a print and a variable file. The file names are ppppnnnn with extensions of PRN and VAR, respectively. The pppp portion of the name is the project prefix obtained from the P argument on the command line. The nnnn is a sequential number assigned in conjunction with data obtained from the project file. The variable file will contain a list of all the variables and their values that are in the Vars array when the program terminates. If there are no specific Vars to be written; this file will be deleted. Otherwise, the VAR file is renamed to pppp.VAR. Consequently, there will be only one VAR file for each prefix.

Process

Recent changes in recommended planning analysis dictate that the simple serial processing may become inadequate. There will need to be "recursive" applications that are driven by intermediate results. Ideally, this process could be written into a large program, and handled as such. But there are disadvantages to that approach (not discussed in this document). A typical simplified highway application would require that the following steps be run (after the network and trip end data have been compiled and checked):

1. Build paths, and add distribution parameters (terminal and intrazonal times).

2. Distribute trip ends according to the paths and user functions.

3. Adjust person trip matrices to account for non-model characteristics, peak period factors, and auto occupancy.

4. Assign trips to the network.

After the application of a series of programs to accomplish this has been completed, you would have to verify the results, and decide if the process needs to be rerun with adjustments, or if the results are satisfactory. The decision process usually will include some type of numerical analysis. If the results of the analysis are not satisfactory, the process may be repeated with some adjustments in the input data, or parameters. Typically, the repeat process is just that: the input data and/or parameters are modified, and the process is resubmitted.

CUBE Voyager simplifies this process by allowing the user to program the process to adjust the data and/or parameters and automatically repeat the entire process, or just selected portions of it. In the simple case, if the final speeds are not acceptable, the process could be looped until speeds come into a reasonable balance, or until it is decided that a proper balance can not be achieved. That is only a simple portion of the capabilities of CUBE Voyager. As the user learns more of its capabilities, he/she will find that he/she can control the process in many innovative ways.

The input is comprised of computational, flow control, program, and system statements. The program begins by reading and editing the CUBE Voyager specific statements. The non-CUBE Voyager statements (system statements, and the statements that follow a RUN statement until its terminating statement) are not edited by CUBE Voyager.

When all CUBE Voyager statements have been edited for basic syntax, and have been stored in the control stack, the program builds a list of variables and their values from all the COMP and LOOP statements and the variables found in the optional VARI file. The list is stored in the Vars array. It then begins processing the control stack at the beginning. Each stack statement is executed, and flow branches to the next appropriate stack statement. When the end of the stack or an EXIT statement is reached, the program terminates.

Stack statements fall into several categories:

• Computational statements — Cause variable values to be updated. Typical control statements are:

  COMP (often invoked by simply: var = )

• Flow control statements - Help to determine which statement is to be performed next. Typical flow control statements are:

  • GOTO

  • :LABEL

  • ONRUNERRORGOTO

  • CLEARERROR

  • LOOP BREAK CONTINUE ENDLOOP

  • IF ELSEIF ELSE ENDIF

  • EXIT

    The program provides the user with the capability to react to fatal returns from Bentleys' programs. When a "RUN PGM=program" statement is executed, the program sets a return code that indicates what type of messages it issued. The return code is either 0 (No messages), 1 (Warning messages), 2 (Fatal messages), or 3 (program aborted); this value is stored in a variable named RETURNCODE. If RETURNCODE is greater than 1, the run is automatically terminated. However, if the user has set the string variable named ONRUNERRORGOTO to point to a legitimate label statement in the script, the run will continue at the labeled statement if the return code is 2.

    At the labeled statement, the user can further control what is to happen with the run. Typically, the user will issue a message, and possibly continue the run. To continue, the user will have to clear the internal RETURNCODE variable, or subsequent tests of the run status may cause termination. The CLEARERROR statement is used to reset the internal return code; it can not be cleared by setting RETURNCODE=. The CLEARERROR statement also provides a keyword to allow the user to resume executing script at the point following the RUN statement that caused control to be switched to the label specified by ONRUNERRORGOTO.

• Program statements — Execute a CUBE Voyager program. A program statement always begins with:

  RUN PGM=

• System statements — Program initiates an operating-system command. A system statement is one in which the first field begins with a *, and is at least two characters long. Typically, system statements are used only in pure DOS applications; they will function within Windows applications, but their use is not recommended.

Example

*COPY*.DATd:

With the capabilities of these statements, the user can cause the stack to be processed in almost any order desired. With the flow control capabilities, stack segments can be repeated until desired results are achieved. A typical example would be the repeated application of a series of programs beginning with trip distribution and progressing through assignment. If the adjusted speeds from the assignment program differ too much from the speeds that were used in the distribution process, the series should be repeated. Another example could be the repeated application of a program with a slightly different set of parameters, or different input files. It is up to the user to control the flow.

Statement tokens (%…% and @…@)

Any statement may contain tokens for substitution. There are two types of tokens: %…% and @…@.

If a CUBE Voyager control statement contains a %…% token, the token is replaced by the value of the operating system (OS) environment variable between the % signs. If there is no matching variable name in the environment, the token is unchanged (the variable name is case insensitive). It should be noted that the environment is a copy of the environment prior to the execution of CUBE Voyager. (Note: Any *SET statements will NOT alter the environment; it is suggested that *SET statements not be used.) There is not much use for %…%, but there might be times where it can be quite helpful.

The @…@ tokens are processed only when the statement is being processed by a program called via the RUN PGM= statement. When a program is called, it is provided access to the .VAR file with the current values from the CUBE Voyager Vars array. The program can update the file when it terminates, but the Vars array is not updated until CUBE Voyager is back in control. If the program reads a control statements that contains a @…@ token, the token is replaced by the value of the file variable named between the @ signs. (Note: The token is replaced literally at the time the program reads the statement; a subsequent change to that variable will not alter the value as read.) If the named variable does not exist in the Vars file, the token is unchanged.

Example

MAX_LOOP = 20
LOOP loop_cnt=1,20
RUN PGM=program
ID = This is the @loop_cnt@ out of @MAX_LOOP@
ENDRUN
ENDLOOP

In this example, MAXLOOP had to be set because LOOP currently accepts only constants for it limits. To keep it entirely generic, MAXLOOP could be set into the environment (SET MAXLOOP=20) prior to launching CUBE Voyager; then the sample could be coded as:

LOOP loop_cnt=1,%MAXLOOP%
RUN PGM=program
ID = This is the @loop_cnt@ out of %MAXLOOP%
ENDRUN
ENDLOOP

The READ statement (see General Syntax) also has capabilities for setting replacement strings in control statements. READ statements are recognized in all CUBE Voyager applications.